HSP Document Library の使い方

HSP Document Library の概要

HSP Document Library (HDL) は、HSP のドキュメントをすべてまとめて 検索・閲覧 するためのブラウザです。

hs ヘルプファイル、txt/HTML ドキュメント、サンプルスクリプトについて、横断検索や相互的な参照をすることができます。

操作一般

【メニュー】

HDL の初期画面に戻るには、メニューの [ホーム] をクリックします。 [ホーム] をクリックすると、初期画面へ戻ると同時に、ドライブ上のドキュメントが更新されていないかチェックが行われます。

文字や画像のサイズを調整する場合は、メニューの [ユーザー補助] から表示設定を選択します。([拡大率] メニューは IE 7 以降がインストールされた環境でのみ動作します。)

【キーワード検索】

HDL のキーワード検索入力欄は、スペース区切りの AND 検索に対応しています。キーワードの前に - (マイナス) 記号を入れると、そのキーワードは NOT 検索されます。

【内蔵 hs ファイルエディタ】

HDL は、hs ファイルエディタを内蔵しています。リファレンスページ 最下部の、"このレコードを編集" をクリックすると、"Help Source Editor" が起動します。

HSP Document Library が読み込むファイル

ライブラリのファイルは、次のディレクトリから検索されます。

HDL のライブラリに新たなドキュメントを追加する場合は、ファイルを doclib ディレクトリに配置することを推奨します。

プラグインやモジュールごとに、doclib ディレクトリ下にカテゴリ ディレクトリを作成し、 その中に関連ドキュメント (hs, hsp サンプル, txt, HTML 文書やそれで使われる画像、スタイルシートなど) をまとめると、 ファイル数が多くなっても管理しやすくなります。

ドキュメント付けされたヘッダファイルとは、ヘッダファイルと hs ファイルが合体したようなタイプのファイルです。 このタイプのファイルは、別途ヘルプファイルを用意しなくても、common ディレクトリにヘッダファイルを追加するだけでリファレンスマニュアルが利用できるようになります。

HSP Document Library の仮想ドキュメントツリー

HDL では、読み込まれたファイルの集合を ライブラリ と呼びます。 ライブラリは リファレンス, ドキュメント, サンプル という 3 つの セクション に分かれます。 それぞれのセクションは、さらに カテゴリ に細分化されます。カテゴリの下に、コンテンツ本体である ページ があります。

(仮想ドキュメントツリー 概念図)

.hs ヘルプファイルの内容は、リファレンスセクションに振り分けられます。 リファレンスセクション内のカテゴリは、使用プラグインごとに分けられます。

.txt .htm .html ファイルは、ドキュメントセクションに振り分けられます。

.hsp ファイルは、サンプルセクションに振り分けられます。 ドキュメントセクションとサンプルセクション内のカテゴリは、実際にファイルが置かれているディレクトリ名で分けられます。 サブディレクトリに属していないファイルは、「標準カテゴリ」に区分されます。

common ディレクトリにドキュメント付けされたヘッダファイル (.as .hsp) がある場合は、その内容はリファレンスセクションに区分されます。

HSP Document Library のドキュメント関連機能

ここからは、ドキュメントの作成者向けに、HDL がサポートするドキュメント処理関連の機能などについて説明します。

hs ファイルの書式

HDL は、リファレンスマニュアル用のヘルプファイルとして hs 形式のファイルをサポートしています。

hs ファイルの書式については、HS_BIBLE.txt を参照してください。

なお、HDL の表示上、命令数が 5 個未満のプラグイン/モジュールは、「その他」として区分されます。

ドキュメント作成上の推奨事項

HDL は、基本的には処理されるドキュメントについて特別なルールを要求しませんが、 ユーザーにとって読みやすいドキュメントが作成されるよう、ドキュメント作成上のゆるやかな推奨事項を取り決めています。

ドキュメント作成のための推奨ルールは、HDL ドキュメントルール にまとめられています。

ドキュメントのサムネイル表示

HDL は、目的のドキュメントやサンプルスクリプトを一覧から見つけやすくするために、サムネイル画像の表示をサポートしています。

ドキュメントファイル (.hsp .htm .html .txt) のディレクトリより配下に thumbs ディレクトリを作成し、対象のドキュメントファイル名 + 画像ファイルの拡張子 の画像ファイルを置くと、 ドキュメントファイルのサムネイル画像として認識されます。サムネイル画像として利用可能なファイルの種類は、BMP, PNG, JPG, GIF です。 推奨画像サイズは、256 x 256 ピクセル以内です。

#module ; スクリプト終了時にスクリーンショット bmp を保存
#deffunc hoge onexit
	bmpsave __FILE__ + ".bmp" ; この画像をあとで縮小
	return
#global

ヘッダファイルと hs ドキュメンテーションコメント

HDL は、common ディレクトリ下のヘッダファイル (.as .hsp) を、ドキュメント付けされたヘッダファイルとして読み込みます。

ドキュメント付けされたヘッダファイルとは、ヘッダファイルに hs 形式のドキュメンテーションコメントを追加した形式のファイルで、 ヘッダファイルとしての機能とリファレンスマニュアルとしての機能をあわせ持ったファイルをさします。

HSP スクリプト中にドキュメンテーションコメントを記入する場合、下記のような書式を使用します。 このスクリプトは、HSP スクリプトとしても hs ヘルプファイルとしてもその仕様を満たし、どちらの形式としても正しく処理されます。

;============================================================
; ドキュメンテーションコメントつきヘッダファイル
;============================================================
/* 〜 モジュール情報 (hs デフォルトレコード)
%dll
d3module

%ver
1.67

%date
2008/05/01

%*/ ; <--- これ以降は hs ファイルとしてはコメントになる
;------------------------------------------------------------

#module

;===========================================================
/* 〜 ドキュメント部分
%index
d3setcam
カメラ位置設定

%prm
x1, y1, z1, x2, y2, z2

%inst
カメラの座標 x1, y1, z1 と向き (ターゲット位置 x2, y2, z2) 設定します。

%group
3D 制御命令

%*/
;------------------------------------------------------------
; 〜 実装部分
#deffunc d3setcam double p1, double p2, double p3, double p4, double p5, double p6
	//
	return
//
#global

ドキュメンテーションコメントは、HSP スクリプトの複数行コメント (/* 〜 */) 内に、hs ヘルプファイルの書式仕様にしたがって記述します。 この、hs 形式のフィールドタグを含む複数行コメントを、ドキュメントブロックと呼びます。

ドキュメントブロックの終了部分は、% 記号を使って、以降が hs 形式としてコメントとなるように処理します。 hs 形式では、定義されていないフィールドタグがあると、以降の行はコメントとみなされます。 この処理を忘れると、HSP スクリプト部分まで hs ドキュメントの一部として認識されてしまう可能性があります。

この部分の記述は、下記のいずれかの書き方を推奨します。

%*/

%rem
*/

ドキュメントブロックの中では、ドキュメントとして複数行コメント (/* 〜 */) を表現することはできません。

このルールに従って書かれたファイルは、拡張子を .hs に変更するだけで、 ドキュメンテーションコメントをサポートしない hs ヘルプツールからも読み込むことが出来ます。

hs ファイルのインライン HTML

HDL には、hs ファイルの %inst フィールド内で "html{" と書いた行から "}html" と書いた行までの間を、ダイレクトに HTML として表示する「インライン HTML」という機能があります。

これは hs ファイルとしての仕様ではなく HDL の表示上の仕様で、従来の HSP HELP Browser II でサポートされていた機能と同等のものです。 この機能により、hs ファイルで HTML の表現を一部利用することができます。

; hs ファイル書式例

%index
stickf
キー入力情報取得

%inst
stickf 関数は、以下のような複数のキーの状態の OR 値を返します。
html{
<table border=1>
<tr><th>値</th><th>キー</th></tr>
<tr><td>1</td><td>カーソルキー左(←)</td></tr>
<tr><td>2</td><td>カーソルキー上(↑)</td></tr>
<tr><td>4</td><td>カーソルキー右(→)</td></tr>
<tr><td>8</td><td>カーソルキー下(↓)</td></tr>
<tr><td>16</td><td>スペースキー</td></tr>
<tr><td>32</td><td>Enterキー</td></tr>
<tr><td>64</td><td>Ctrlキー</td></tr>
<tr><td>128</td><td>ESCキー</td></tr>
</table>
}html

インライン HTML の区間について、中の HTML の書式は HDL によってチェックされません。 誤った HTML が記述されているとページ全体のレイアウトが崩れたりする可能性もありますので、hs データの配布などを行う場合は十分にチェックを行ってください。 また、情報の意味づけに関係しない、装飾的な目的での HTML の使用は避けるようにしてください。

インライン HTML ではアクティブスクリプト (javascript 等) の記述を行わないでください。 スクリプトの実行に関するいくつかのキーワードは、使用を制限されています。インライン HTML で使用した要素のスタイルは、外部 CSS の影響を受ける場合があります。

HDL の出力ページのドキュメントタイプは、HTML 4.01 Transitional です。

アップデート情報

HDL の最新バージョンは、http://sprocket.babyblue.jp/ で公開されています。